<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
    <title>Collection File Structure</title>
    <meta name="order" content="1" />
    <meta name="toc" content="true" />
    <meta name="toc-max" content="4" />
  </head>
  <body>
    <h2>Stencil Collection Structure and File Format</h2>
    <h3>Stencil Collection Structure </h3>
    <p> A stencil collection is usually distributed as a single ZIP
      archive containing all related files for that collection. </p>
    <p> This collection ZIP archive has one main XML file named
      (exactly) <i>Definition.xml</i> and other optional files or
      sub-directories containing supporting files for the main XML
      (mainly for icon files). </p>
    <p> The <i>Definition.xml</i> file name is <i>case-sensitive</i>
      and is the only required file for a collection. All other files
      can be omitted when not needed. </p>
    <h3>Format of the <code>Definition.xml</code> file</h3>
    <p> Each <i>Definition.xml</i> file defines a collection of
      stencils by providing collection information and all stencil
      definitions. This is just a standard XML file that can be created
      by virtually any text editor you have in your system. </p>
    <h4>General Structure </h4>
    <p> The <i>Definition.xml</i> file has the following structure: </p>
<pre name="code" class="xml"><![CDATA[
<Shapes xmlns="http://www.evolus.vn/Namespace/Pencil"
        xmlns:p="http://www.evolus.vn/Namespace/Pencil"
        xmlns:svg="http://www.w3.org/2000/svg"
        xmlns:xlink="http://www.w3.org/1999/xlink"

        id="your_collection_id"
        displayName="Display name of your collection"
        description="More description about this collection"
        author="Names of the authors"
        url="Optional URL to its web page">
        
        <Properties>
            <!-- Collection properties -->
        </Properties>
        <Script>
            <!-- Shared script code for your collection -->
        </Script>
        
        <!-- Shape and shortcut definitions -->
        <Shape>...</Shape>
        <Shortcut>...</Shortcut>
        
</Shapes>
]]>
</pre>
    <p> The following list summarizes the format: </p>
    <ul>
      <li>
        <p> The out-most tag is <code><i><b>&lt;Shapes&gt;</b></i></code> with the
          namespace URI is <i>http://www.evolus.vn/Namespace/Pencil</i>
        </p>
      </li>
      <li>
        <p> Information about the collection are specified by the <code><i><b>&lt;Shapes&gt;</b></i></code>
          node's attributes: <i>id, displayName, description, author </i>and
          <i>url</i> </p>
      </li>
      <li>
        <p>
            A collection may have properties that can referenced as initial values for shape properties. These
            properties should be defined in the <code><strong><em>&lt;Properties&gt;</em></strong></code> section of the collection.
        </p>
      </li>
      <li>
        <p>
            A collection may have also shared JavaScript code that can be re-used across its shapes. These code can be defined
            in the <code><i><b>&lt;Script&gt;</b></i></code> tag.
        </p>
      </li>
      <li>
        <p> Each shape in the collection is defined in a separate <code><i><b>&lt;Shape&gt;</b></i></code>
          tag placed right under the root <code><i><b>&lt;Shapes&gt;</b></i></code>
          tag. Please refer the next section for details on definition
          structure for a shape. </p>
      </li>
      <li>
        <p>
            Beside shapes, a collection may contain also shortcuts which are references to another shape with different
            default values to its properties. Shortcuts are defined in <code><strong><em>&lt;Shortcut&gt;</em></strong></code> tags.
        </p>
      </li>
    </ul>
    <h4>The <code>&lt;Shape&gt;</code> tag</h4>
    <p> Each shape in a collection is defined in a <code>&lt;Shape&gt;</code>
      tag with the following structure: </p>
<pre name="code" class="xml"><![CDATA[
    <Shape id="shape_id" displayName="Shape display name"  
           icon="url_to_shape_icon">  
      <Properties>  
        <PropertyGroup name="Property group name">  
          <Property name="..."
                    displayName="..."  
                    type="...">{Default value}</Property>  
          <Property>...</Property>  
          <Property>...</Property>  
        </PropertyGroup>  
        <PropertyGroup>...</PropertyGroup>
      </Properties>  
      <Behaviors>  
        <For ref="target_element_id">
          <!-- Single argument behavior, for example 'Font' -->
          <Behavior_Name>JS expression for input value<Behavior_Name>
          
          <!-- Multi argument behavior, for example 'BoxFit' -->
          <Other_Behavior_Name>  
            <Arg>JS expression for argument 1</Arg>  
            <Arg>JS expression for argument 2</Arg>
            ...  
          </Other_Behavior_Name>  
        </For>  
      </Behaviors>  
      <p:Content xmlns:p="http://www.evolus.vn/Namespace/Pencil"  
                 xmlns="http://www.w3.org/2000/svg">  
        <!-- SVG content of the stencil 
             Each element can be identified by the 'id' attribute
             which is referenced by the 'ref' attributes in the Behavior
             sections defined above -->  
      </p:Content>  
    </Shape>  
]]></pre>
    <h4>The collection's <code>&lt;Properties&gt;</code> tag</h4>
    <p>
        The collection's <code>&lt;Properties&gt;</code> tag is used as the place to defined properties at the collection
        level. This is the recommended way for stencil author to define changable default values for shape properties.
        Properties defined in this section can be referenced in the stencil's code using the <code>$$</code> syntax and
        can be changed by users by right-clicking on the collection in the collection pane.
    </p>
    <p>
        The structure of this section is similar to the <code>&lt;Properties&gt;</code> section in the stencil level:
    </p>
<pre name="code" class="xml"><![CDATA[
<Shapes ...>
    ...
    <Properties>
        <PropertyGroup name="Text">
            <Property displayName="Default Text Font"
                      name="defaultTextFont"
                      type="Font">Helvetica|normal|normal|12px</Property>
            <Property displayName="Default Text Color"
                      name="defaultTextColor"
                      type="Color">#000000ff</Property>
        </PropertyGroup>
    </Properties>
    ...
</Shapes>
]]></pre>

    <h4>The collection's <code>&lt;Script&gt;</code> tag</h4>
    <p>
        Collection <code>&lt;Script&gt;</code> tag is used to defined shared JavaScript code within a collection.
        JavaScript code in this section will be executed when the collection is loaded into Pencil. In the execution
        context of these scripts, a special object named <code>collection</code> is available and is virtually bound
        to the collection itself. This object is also available in the execution of behavior and action code
        of each stencil so developers can use it as a shared object for storing function definitions and constants that need to be
        used across stencils.  
    </p>
<pre name="code" class="xml"><![CDATA[
<Shapes ...>
    ...
    <Script commnent="Shared collection objects">
        //sample constant definition
        collection.DEFAULT_PADDING = 5;
        
        //sample shared function
        collection.gradToDeg = function (grad) {
            return grad * 180 / Math.PI;
        };
    </Script>
    ...
</Shapes>
]]></pre>
    <h4>The collection's <code>&lt;Shortcut&gt;</code> tag</h4>
    <p>
        The <code>&lt;Shortcut&gt;</code> tag creates an alias to an existing stencil and provides different
        initial values to that stencil's properties. The structure of this tag is described below:
    </p>
<pre name="code" class="xml"><![CDATA[
<Shapes ...>
    ...
    <Shortcut displayName="Display name"
              icon="..."
              to="[collection_id:]stencil_id">
        <PropertyValue name="property_name">new default value</PropertyValue>
        <PropertyValue>...</PropertyValue>
        <PropertyValue>...</PropertyValue>
    </Shortcut>
    ...
</Shapes>
]]></pre>

  </body>
</html>
